Skip to main content
Version: 1.0.0

aggregateDailySessionsCatalogs

Function Names: aggregateDailySessionsCatalogs / testAggregateSessionsForCatalogs

Author: Domenico Cerone Creation Date: 25/09/2025
Last Reviewer: Domenico Cerone

Trigger: Scheduler (onSchedule - daily at 02:10) / HTTPS (onRequest)

Purpose: Daily session aggregation system for AR/VTO (Virtual Try-On) analytics. Collects and processes user session data from 6 Firebase collections (3 old + 3 new) for all brands, converts old format to new format, and generates comprehensive analytics stored in AggregateSessions collection.

Detailed Functionality​

1. DATA COLLECTION AND CONVERSION SYSTEM V2​

  • Old Collections: Sessione, Sessione_WebVto, Sessione_Visualizzatori3d
  • New Collections: Session_Apps, Session_WebVto, Session_3DViewer
  • Conversion Direction: Old format → New format (future-ready approach)
  • Processing: Converts old collection data structure to match new collections format

2. COLLECTION MAPPING AND PROPERTY CONVERSION​

Base Session Properties:

  • ref_catalogo → catalogRef (Firebase reference to string ID)
  • data_inizio_sessione → sessionStartDate (identical date format)
  • device_id → deviceId (property name change)
  • is_first_session → isFirstSession (snake_case to camelCase)
  • total_time → totalTime (snake_case to camelCase)
  • lista_occhiali_visualizzati → list_viewed_products (structure and name change)

Product Properties (within lista_occhiali_visualizzati → list_viewed_products):

  • nome_occhiale → productName (property name change)
  • lineaRef/lineaRefs → lineTagRef (with ID extraction from object)
  • glassesRef/glassesRefs → catalogProductRef (with ID extraction from object)
  • listaModelliProvati → list_tried_variants (structure and name change)

Variant Properties (within listaModelliProvati → list_tried_variants):

  • modelRef → catalogVariantRefs (with ID extraction from object)
  • tagliaRef → sizeRef (with ID extraction from object)
  • totalSeconds → totalSeconds (identical property)

3. DIFFERENTIAL QUERYING STRATEGY​

Old Collections Query (Sessione, Sessione_WebVto, Sessione_Visualizzatori3d):

  • Filter by: ref_catalogo (Firebase document reference to Brand collection)
  • Order by: data_inizio_sessione
  • Properties: ref_catalogo, data_inizio_sessione, device_id, device, device_os, is_first_session, total_time, lista_occhiali_visualizzati

New Collections Query (Session_Apps, Session_WebVto, Session_3DViewer):

  • Filter by: catalogRef (string brand ID)
  • Order by: sessionStartDate
  • Properties: catalogRef, sessionStartDate, deviceId, device, device_os, isFirstSession, totalTime, list_viewed_products

4. DATA UNION BY SERVICE​

  • APP Service: Combines Sessione (converted) + Session_Apps
  • WEB VTO Service: Combines Sessione_WebVto (converted) + Session_WebVto
  • 3D VIEWER Service: Combines Sessione_Visualizzatori3d (converted) + Session_3DViewer

5. METRICS CALCULATION SYSTEM​

Session Filtering:

  • Minimum session duration: 4 seconds
  • Maximum session duration: 450 seconds
  • Filters out invalid or extremely short sessions

Aggregate Metrics:

  • Total sessions and unique users
  • Average session time and engagement time
  • Product line analysis (eyewear lines)
  • Individual eyewear model analysis
  • Specific variant analysis (frame/lens colors)
  • Device/browser distribution analysis

6. VARIANT DATA ENRICHMENT​

Old Sessions (from Modello collection):

  • Uses brandCodePath to query Modello collection
  • Queries with loadingId range filtering
  • Retrieves frameColor, sku, eanCode, upcCode from Modello documents
  • Fallback to CataloguesVariants if frameColor missing in Modello

New Sessions (from CataloguesVariants collection):

  • Direct lookup using catalogVariantRefs
  • Retrieves esaColorFramePrimary, esaColorFrameSecondary, esaColorLensesPrimary, esaColorLensesSecondary, frameColor, sku, eanCode, upcCode

7. NEW STORAGE STRUCTURE IN AGGREGATESESSIONS​

Main Document Properties:

  • list_lines (instead of lineArray) - product line analytics
  • All other properties remain identical: totalSessions, totalUniqueUsers, newUsersCount, avgSessionTime, averageSessionsPerUser, avgEngagementTime, service, date, catalog, deviceData

Sub-collection Structure:

  • Collection name: ProductsAnalytics (instead of glassesAnalytics)
  • Document properties:
    • list_products (instead of glassesArray) with properties:
      • productRef (instead of glassesRef)
      • productName (instead of nome_occhiale)
      • time, visualization, numberOfSessions, numberOfUniqueUsers, newUsersCount, averageSessionTime, averageSessionsPerUser, averageEngagementTime, lineRef (identical)
    • list_variants (instead of variantsArray) with properties:
      • variantRef (instead of modelRef)
      • productRef (instead of glassesRef)
      • sizeRef (for old sessions only - size ID)
      • size (numeric size value)
      • lineRef, esaColorFramePrimary, esaColorFrameSecondary, esaColorLensesPrimary, esaColorLensesSecondary, sku, eanCode, upcCode, time, visualization, numberOfSessions, numberOfUniqueUsers, newUsersCount, averageSessionTime, averageSessionsPerUser, averageEngagementTime (identical)

8. MEMORY OPTIMIZATION AND PERFORMANCE​

Batch Processing:

  • Processes brands in batches of 3 to limit memory usage
  • Implements forced garbage collection between batches
  • Memory monitoring with automatic recovery mechanisms

Retry Logic:

  • Intelligent retry system with exponential backoff
  • Up to 5 attempts per brand-date combination
  • Memory cleanup between retry attempts

Resource Management:

  • 4GB memory allocation for optimal performance
  • 30-minute timeout for complete processing
  • Automatic garbage collection when memory usage exceeds 2GB

9. AUTOMATED SCHEDULING​

  • Execution Time: Daily at 02:10 (Europe/Rome timezone)
  • Processing Date: Previous day's data (yesterday)
  • Scope: All brands in Brand collection
  • Retry Policy: Up to 2 retry attempts for failed executions

10. COMPREHENSIVE ERROR HANDLING​

  • Individual brand failure doesn't stop overall processing
  • Detailed logging for each processing stage
  • Memory usage tracking and optimization
  • Success/failure statistics for monitoring

Input (Payload)​

Scheduler Function (aggregateDailySessionsCatalogs)​

  • Automatic trigger: No input required (scheduled execution)
  • Processing date: Previous day (yesterday) calculated automatically
  • Scope: All brands in Brand collection

HTTP Function (testAggregateSessionsForCatalogs)​

Method: POST/GET

Headers:

  • Content-Type: application/json (for POST requests)

Body (POST) or Query Parameters (GET):

{
  "brandId": "rBf3geYISXtkue0WGgFT",
  "date": "2024/07/01"
}

Parameters:

  • brandId (string, required): Unique identifier of the brand/catalog
  • date (string, optional): Date in format YYYY/MM/DD (defaults to yesterday if not provided)

Output (Success)​

Scheduler Function​

{
  "success": true,
  "processed": true,
  "duration": "15 minutes",
  "brandsProcessed": 25,
  "brandsSkipped": 1,
  "successRate": "96%"
}

HTTP Function​

{
  "success": true,
  "message": "Aggregazione V2 completata con successo per brand rBf3geYISXtkue0WGgFT",
  "brandId": "rBf3geYISXtkue0WGgFT",
  "date": "2024/07/01",
  "servicesProcessed": 3,
  "collectionsRead": ["Sessione", "Sessione_WebVto", "Sessione_Visualizzatori3d", "Session_Apps", "Session_WebVto", "Session_3DViewer"],
  "conversionDirection": "Vecchie collezioni → Formato nuove collezioni",
  "collectionsInfo": {
    "oldCollections": {
      "Sessione": 25,
      "Sessione_WebVto": 89,
      "Sessione_Visualizzatori3d": 1
    },
    "newCollections": {
      "Session_Apps": 25,
      "Session_WebVto": 58,
      "Session_3DViewer": 0
    }
  },
  "outputCollection": "AggregateSessions",
  "newStructure": {
    "mainDocument": "list_lines (invece di lineArray)",
    "subCollection": "ProductsAnalytics (invece di glassesAnalytics)",
    "subDocumentFields": "list_products, list_variants (invece di glassesArray, variantsArray)"
  },
  "results": [
    {
      "documentId": "abc123",
      "service": "APP",
      "totalSessions": 45,
      "totalUniqueUsers": 32,
      "newUsersCount": 15,
      "avgSessionTime": {"minutes": 2, "seconds": 30},
      "list_lines": [...],
      "ProductsAnalytics": [...]
    }
  ]
}

Response Properties:

  • success (boolean): Indicates if the operation was completed successfully
  • message (string): Descriptive message about the operation result
  • brandId (string): Brand identifier that was processed
  • date (string): Date that was processed
  • servicesProcessed (number): Number of services (APP, WEB VTO, 3D VIEWER) processed
  • collectionsRead (array): List of all 6 collections that were queried
  • conversionDirection (string): Indicates old to new format conversion
  • collectionsInfo (object): Document counts from each collection
  • outputCollection (string): Target collection where results are stored
  • newStructure (object): Description of the new storage structure
  • results (array): Array of processed documents with analytics data

Testing​

URL (if HTTPS): http://127.0.0.1:5001/arshadesstaging/europe-central2/testAggregateSessionsForCatalogs

Test con Emulator:

  1. Avviare l'emulatore Firebase: firebase emulators:start --only functions
  2. Assicurarsi di usare Node.js versione 20: nvm use 20
  3. Testare con curl:
curl -X POST "http://127.0.0.1:5001/arshadesstaging/europe-central2/testAggregateSessionsForCatalogs" \
-H "Content-Type: application/json" \
-d '{
  "brandId": "rBf3geYISXtkue0WGgFT",
  "date": "2024/07/01"
}'

Postman Testing:

  • Metodo: POST
  • URL: http://127.0.0.1:5001/arshadesstaging/europe-central2/testAggregateSessionsForCatalogs
  • Headers:
    • Key: Content-Type
    • Value: application/json
  • Body: raw JSON (vedi esempi sopra)

Deploy Command​

firebase deploy --only functions:aggregateDailySessionsCatalogs,functions:testAggregateSessionsForCatalogs

URL di Produzione​

Scheduled Function: https://europe-central2-arshades-7e18a.cloudfunctions.net/aggregateDailySessionsCatalogs (Solo riferimento - non direttamente chiamabile)

Test Function: https://europe-central2-arshades-7e18a.cloudfunctions.net/testAggregateSessionsForCatalogs